JavaScript Temporal API: Nykyaikainen päivämäärien ja aikojen käsittely globaalille yleisölle

JavaScriptin `Date`-olio on pitkään ollut kehittäjien turhautumisen lähde. Sen muuttuvuus (mutability), epäjohdonmukainen API ja heikko aikavyöhyketuki ovat johtaneet lukuisten kirjastojen, kuten Moment.js:n ja date-fns:n, syntyyn paikkaamaan puutteita. Nyt Temporal API:n myötä JavaScript tarjoaa modernin, sisäänrakennetun ratkaisun päivämäärien ja aikojen käsittelyyn selkeämmin ja tarkemmin. Tämä artikkeli tarjoaa kattavan yleiskatsauksen Temporal API:sta keskittyen sen ominaisuuksiin, hyötyihin ja käyttöön erilaisissa kansainvälisissä ympäristöissä.

Mikä on Temporal API?

Temporal API on uusi, globaali olio JavaScriptissä, joka on suunniteltu korjaamaan `Date`-olion puutteet. Se tarjoaa selkeän, muuttumattoman (immutable) API:n päivämäärien, aikojen, aikavyöhykkeiden ja kalenterijärjestelmien käsittelyyn. Keskeistä on, että se pyrkii esittämään päivämäärä- ja aikakäsitteet tavalla, joka vastaa paremmin todellista käyttöä ja odotuksia, tehden kansainvälistämisestä huomattavasti suoraviivaisempaa.

Tärkeimmät ominaisuudet:

• Muuttumattomuus (Immutability): Temporal-oliot ovat muuttumattomia, mikä tarkoittaa, että operaatiot, kuten päivien tai kuukausien lisääminen, palauttavat uusia olioita alkuperäisen muokkaamisen sijaan. Tämä poistaa yleisen bugien lähteen ja tekee koodista helpommin ymmärrettävää.
• Selkeä API: Temporal tarjoaa johdonmukaisen ja intuitiivisen API:n yleisimpiin päivämäärä- ja aikaoperaatioihin.
• Aikavyöhyketuki: Temporal sisältää vankan tuen aikavyöhykkeille, mikä mahdollistaa päivämäärien ja aikojen käsittelyn eri paikoissa ilman vanhan `Date`-olion monimutkaisuuksia. Se käyttää IANA-aikavyöhyketietokantaa, mikä takaa tarkan ja ajantasaisen tiedon.
• Kalenterijärjestelmät: Gregoriaanisen kalenterin lisäksi Temporal tukee vaihtoehtoisia kalenterijärjestelmiä, vastaten erilaisten kulttuurien ja alueiden tarpeisiin.
• Parempi tarkkuus: Temporal tarjoaa nanosekunnin tarkkuuden, mikä korjaa millisekuntipohjaisen `Date`-olion rajoitukset.

Temporalin perusoliot

Temporal API esittelee useita uusia oliotyyppejä. Tässä on joitakin keskeisimmistä:

• `Temporal.PlainDate`: Edustaa päivämäärää (vuosi, kuukausi, päivä) ilman aikavyöhykettä.
• `Temporal.PlainTime`: Edustaa aikaa (tunti, minuutti, sekunti, millisekunti, mikrosekunti, nanosekunti) ilman päivämäärää tai aikavyöhykettä.
• `Temporal.PlainDateTime`: Edustaa päivämäärää ja aikaa ilman aikavyöhykettä.
• `Temporal.ZonedDateTime`: Edustaa päivämäärää ja aikaa tietyllä aikavyöhykkeellä.
• `Temporal.Instant`: Edustaa tiettyä ajanhetkeä, mitattuna nanosekunteina Unix-epochista (1. tammikuuta 1970 UTC).
• `Temporal.TimeZone`: Edustaa aikavyöhykettä.
• `Temporal.Duration`: Edustaa ajanjaksoa (esim. 2 tuntia, 30 minuuttia).
• `Temporal.YearMonth`: Edustaa vuotta ja kuukautta.
• `Temporal.MonthDay`: Edustaa kuukautta ja päivää.

Päivämäärien käsittely

`Temporal.PlainDate`-olion luominen

Voit luoda `Temporal.PlainDate`-olion konstruktorilla:

            const plainDate = new Temporal.PlainDate(2024, 10, 27); // Vuosi, Kuukausi (1-12), Päivä
console.log(plainDate.toString()); // Tuloste: 2024-10-27
            

              
                Copy
              
            
          

Voit myös käyttää `from`-metodia, joka hyväksyy merkkijonon ISO 8601 -muodossa:

            const plainDateFromString = Temporal.PlainDate.from('2024-10-27');
console.log(plainDateFromString.toString()); // Tuloste: 2024-10-27
            

              
                Copy
              
            
          

Päivämäärän osien hakeminen

Yksittäisiin päivämäärän osiin pääsee käsiksi ominaisuuksilla, kuten `year`, `month` ja `day`:

            console.log(plainDate.year); // Tuloste: 2024
console.log(plainDate.month); // Tuloste: 10
console.log(plainDate.day); // Tuloste: 27
            

              
                Copy
              
            
          

Päivämääräaritmetiikka

Päivien, viikkojen, kuukausien tai vuosien lisäämiseen ja vähentämiseen käytetään `plus`- ja `minus`-metodeja. Nämä metodit palauttavat uuden `Temporal.PlainDate`-olion:

            const nextWeek = plainDate.plus({ days: 7 });
console.log(nextWeek.toString()); // Tuloste: 2024-11-03

const lastMonth = plainDate.minus({ months: 1 });
console.log(lastMonth.toString()); // Tuloste: 2024-09-27
            

              
                Copy
              
            
          

Päivämäärien vertailu

Päivämääriä voi verrata `compare`-metodilla:

            const date1 = new Temporal.PlainDate(2024, 10, 27);
const date2 = new Temporal.PlainDate(2024, 11, 15);

console.log(Temporal.PlainDate.compare(date1, date2)); // Tuloste: -1 (date1 on aiemmin kuin date2)
            

              
                Copy
              
            
          

Aikojen käsittely

`Temporal.PlainTime`-olion luominen

Voit luoda `Temporal.PlainTime`-olion konstruktorilla:

            const plainTime = new Temporal.PlainTime(10, 30, 0); // Tunti, Minuutti, Sekunti
console.log(plainTime.toString()); // Tuloste: 10:30:00
            

              
                Copy
              
            
          

Tai käytä `from`-metodia ISO 8601 -aikamerkkijonolla:

            const plainTimeFromString = Temporal.PlainTime.from('10:30:00');
console.log(plainTimeFromString.toString()); // Tuloste: 10:30:00
            

              
                Copy
              
            
          

Ajan osien hakeminen

            console.log(plainTime.hour); // Tuloste: 10
console.log(plainTime.minute); // Tuloste: 30
console.log(plainTime.second); // Tuloste: 0
            

              
                Copy
              
            
          

Aika-aritmetiikka

            const later = plainTime.plus({ minutes: 15 });
console.log(later.toString()); // Tuloste: 10:45:00
            

              
                Copy
              
            
          

Päivämäärän ja ajan yhteiskäsittely

`Temporal.PlainDateTime`-olion luominen

Voit luoda `Temporal.PlainDateTime`-olion suoraan tai yhdistämällä `Temporal.PlainDate`- ja `Temporal.PlainTime`-oliot:

            const plainDateTime = new Temporal.PlainDateTime(2024, 10, 27, 10, 30, 0);
console.log(plainDateTime.toString()); // Tuloste: 2024-10-27T10:30:00

const date = new Temporal.PlainDate(2024, 10, 27);
const time = new Temporal.PlainTime(10, 30, 0);
const combinedDateTime = date.toPlainDateTime(time);
console.log(combinedDateTime.toString()); // Tuloste: 2024-10-27T10:30:00
            

              
                Copy
              
            
          

Aikavyöhykkeet

Aikavyöhykkeiden oikea käsittely on ratkaisevan tärkeää sovelluksille, jotka palvelevat käyttäjiä eri paikoissa. Temporal API tarjoaa vankan aikavyöhyketuen `Temporal.ZonedDateTime`- ja `Temporal.TimeZone`-olioiden kautta.

`Temporal.ZonedDateTime`-olion luominen

`Temporal.ZonedDateTime`-olion luomiseen tarvitaan `Temporal.PlainDateTime` ja aikavyöhyketunniste. Aikavyöhyketunnisteet perustuvat IANA-aikavyöhyketietokantaan (esim. `America/Los_Angeles`, `Europe/London`, `Asia/Tokyo`).

            const plainDateTime = new Temporal.PlainDateTime(2024, 10, 27, 10, 30, 0);
const timeZone = 'America/Los_Angeles';
const zonedDateTime = plainDateTime.toZonedDateTime(timeZone);
console.log(zonedDateTime.toString()); // Tuloste: 2024-10-27T10:30:00-07:00[America/Los_Angeles] (Poikkeama riippuu kesäaikasäännöistä)

            

              
                Copy
              
            
          

Vaihtoehtoisesti `Temporal.ZonedDateTime` voidaan luoda `Instant`-oliosta.

            const instant = Temporal.Instant.fromEpochSeconds(1666866600); // Esimerkkileima
const zonedDateTimeFromInstant = instant.toZonedDateTimeISO(timeZone); // Aikavyöhyke kuten 'America/Los_Angeles'
console.log(zonedDateTimeFromInstant.toString());
            

              
                Copy
              
            
          

Muuntaminen aikavyöhykkeiden välillä

Voit muuntaa `Temporal.ZonedDateTime`-olion toiselle aikavyöhykkeelle `withTimeZone`-metodilla:

            const newTimeZone = 'Europe/London';
const zonedDateTimeInLondon = zonedDateTime.withTimeZone(newTimeZone);
console.log(zonedDateTimeInLondon.toString()); // Tuloste: 2024-10-27T18:30:00+01:00[Europe/London]
            

              
                Copy
              
            
          

Aikavyöhykepoikkeamien käsittely

`Temporal.TimeZone`-olion `getOffsetStringFor`-metodi antaa poikkeamamerkkijonon tietylle `Temporal.Instant`-oliolle:

            const timeZoneObject = new Temporal.TimeZone(timeZone);
const offsetString = timeZoneObject.getOffsetStringFor(zonedDateTime.toInstant());
console.log(offsetString); // Tuloste: -07:00 (Riippuen kesäaikasäännöistä)
            

              
                Copy
              
            
          

On olennaista käyttää oikeita IANA-aikavyöhyketunnisteita tarkkojen laskelmien varmistamiseksi. Näitä tunnisteita ylläpidetään ja päivitetään säännöllisesti vastaamaan kesäajan ja aikavyöhykerajojen muutoksia.

Kestot (Durations)

`Temporal.Duration`-olio edustaa ajanjaksoa. Sitä voidaan käyttää ajan lisäämiseen tai vähentämiseen päivämääristä ja ajoista.

`Temporal.Duration`-olion luominen

Voit luoda `Temporal.Duration`-olion konstruktorilla, määrittäen vuodet, kuukaudet, päivät, tunnit, minuutit, sekunnit, millisekunnit, mikrosekunnit ja nanosekunnit:

            const duration = new Temporal.Duration(1, 2, 3, 4, 5, 6, 7, 8, 9); // Vuodet, Kuukaudet, Päivät, Tunnit, Minuutit, Sekunnit, Millisekunnit, Mikrosekunnit, Nanosekunnit
console.log(duration.toString()); // Tuloste: P1Y2M3DT4H5M6.007008009S
            

              
                Copy
              
            
          

Tai käyttämällä ISO 8601 -kestomerkkijonoa:

            const durationFromString = Temporal.Duration.from('P1Y2M3DT4H5M6S');
console.log(durationFromString.toString()); // Tuloste: P1Y2M3DT4H5M6S
            

              
                Copy
              
            
          

Kestojen lisääminen päivämääriin ja aikoihin

            const plainDate = new Temporal.PlainDate(2024, 10, 27);
const duration = new Temporal.Duration(0, 0, 7); // 7 päivää
const newDate = plainDate.plus(duration);
console.log(newDate.toString()); // Tuloste: 2024-11-03
            

              
                Copy
              
            
          

Huomaa, että kuukausia tai vuosia sisältävien kestojen lisääminen päivämääriin vaatii tarkkaa harkintaa, koska päivien määrä kuukaudessa tai vuodessa voi vaihdella.

Kalenterijärjestelmät

Temporal API tukee eri kalenterijärjestelmiä gregoriaanisen kalenterin lisäksi. Tämä on ratkaisevan tärkeää sovelluksille, joiden on käsiteltävä päivämääriä erilaisissa kulttuurikonteksteissa. Vaikka tuki on vielä kehittymässä, se tarjoaa perustan tulevalle laajennukselle.

Vaihtoehtoisten kalenterien käyttäminen

Voit käyttää tiettyä kalenteria määrittämällä sen Temporal-olioita luodessasi:

            const hebrewDate = new Temporal.PlainDate(5785, 1, 1, { calendar: 'hebrew' });
console.log(hebrewDate.toString()); // Tarkka tuloste voi vaihdella toteutuksesta ja muotoilusta riippuen. Vaatii polyfillin monissa ympäristöissä tätä kirjoitettaessa.
            

              
                Copy
              
            
          

Tärkeää: Tuki muille kuin gregoriaanisille kalentereille saattaa vaatia polyfillejä tai erityistä selain-/ympäristötukea. Tarkista ajantasaisimmat tiedot Temporal API:n dokumentaatiosta ja selainten yhteensopivuustaulukoista.

Päivämäärien ja aikojen muotoilu

Vaikka Temporal API keskittyy päivämäärä- ja aikamanipulaatioon, muotoilun hoitaa tyypillisesti `Intl.DateTimeFormat`-olio, joka on osa kansainvälistämisen API:ta (Internationalization API). Temporal-oliot toimivat saumattomasti `Intl.DateTimeFormat`:n kanssa.

`Intl.DateTimeFormat`:n käyttäminen

Näin muotoilet `Temporal.PlainDate`-olion `Intl.DateTimeFormat`:n avulla:

            const plainDate = new Temporal.PlainDate(2024, 10, 27);
const formatter = new Intl.DateTimeFormat('en-US', { year: 'numeric', month: 'long', day: 'numeric' });
console.log(formatter.format(plainDate)); // Tuloste: October 27, 2024

const formatterGerman = new Intl.DateTimeFormat('de-DE', { year: 'numeric', month: 'long', day: 'numeric' });
console.log(formatterGerman.format(plainDate)); // Tuloste: 27. Oktober 2024
            

              
                Copy
              
            
          

Voit mukauttaa muotoiluasetuksia tarpeidesi mukaan. `Intl.DateTimeFormat`:n ensimmäinen argumentti on lokaali, joka määrittää muotoilussa käytettävän kielen ja alueelliset käytännöt. Eri lokaalien (esim. 'en-US', 'de-DE', 'fr-FR', 'ja-JP') käyttäminen tuottaa erilaisia tulostusmuotoja.

`Temporal.ZonedDateTime`-olion muotoilu

`Temporal.ZonedDateTime`-olion muotoilu on samanlaista, mutta voit sisällyttää tulosteeseen myös aikavyöhyketietoja:

            const plainDateTime = new Temporal.PlainDateTime(2024, 10, 27, 10, 30, 0);
const timeZone = 'America/Los_Angeles';
const zonedDateTime = plainDateTime.toZonedDateTime(timeZone);

const formatter = new Intl.DateTimeFormat('en-US', { year: 'numeric', month: 'long', day: 'numeric', hour: 'numeric', minute: 'numeric', timeZoneName: 'short' });
console.log(formatter.format(zonedDateTime)); // Tuloste: October 27, 2024, 10:30 AM PDT (Aikavyöhykkeen lyhenne riippuu kesäaikasäännöistä)
            

              
                Copy
              
            
          

Kansainvälistämisen parhaat käytännöt

Kun käsittelet päivämääriä ja aikoja globaalissa kontekstissa, pidä mielessä seuraavat parhaat käytännöt:

• Käytä IANA-aikavyöhyketunnisteita: Käytä aina IANA-aikavyöhyketunnisteita (esim. `America/Los_Angeles`, `Europe/London`) tarkan aikavyöhykekäsittelyn varmistamiseksi.
• Ota huomioon kesäaika: Kesäaika (DST) voi vaikuttaa aikavyöhykepoikkeamiin. Temporal API käsittelee kesäaikasiirtymät automaattisesti.
• Käytä `Intl.DateTimeFormat`-oliota muotoiluun: Käytä `Intl.DateTimeFormat`-oliota päivämäärien ja aikojen muotoiluun käyttäjän lokaalin mukaan.
• Harkitse kalenterijärjestelmiä: Jos sovelluksesi tulee tukea käyttäjiä eri kulttuurikonteksteissa, harkitse vaihtoehtoisten kalenterijärjestelmien käyttöä.
• Tallenna päivämäärät ja ajat UTC-aikana: Tallennettaessa päivämääriä ja aikoja tietokantaan on parasta tallentaa ne UTC-ajassa (Coordinated Universal Time) aikavyöhykeongelmien välttämiseksi. Muunna ne sitten paikalliseen aikaan näyttämistä varten. Temporal tarjoaa metodeja UTC-ajan ja paikallisen ajan välisiin muunnoksiin.
• Testaa perusteellisesti: Testaa sovellustasi eri aikavyöhykkeillä, lokaaleilla ja kalenterijärjestelmillä varmistaaksesi, että se toimii oikein kaikille käyttäjille.

Temporal API:n vertailu vanhaan Date-olioon

Tässä taulukossa korostetaan Temporal API:n keskeisiä eroja ja etuja verrattuna vanhaan `Date`-olioon:

Selaintuki ja polyfillit

Koska kyseessä on suhteellisen uusi API, Temporal API:n selaintuki kehittyy edelleen. Tarkista uusimmat selainten yhteensopivuustaulukot (esim. MDN Web Docsista) nähdäksesi, mitkä selaimet ja ympäristöt tukevat sitä natiivisti. Vanhemmille selaimille tai ympäristöille ilman natiivitukea voit käyttää polyfillejä tarjoamaan Temporal API:n toiminnallisuuden. Hae verkosta "Temporal API polyfill" löytääksesi sopivia vaihtoehtoja.

Yhteenveto

JavaScriptin Temporal API on merkittävä edistysaskel päivämäärien ja aikojen käsittelyssä JavaScriptissä. Sen muuttumattomuus, selkeä API, vankka aikavyöhyketuki ja kalenterijärjestelmäominaisuudet tekevät siitä tehokkaan työkalun kehittäjille, jotka rakentavat sovelluksia, joiden on käsiteltävä päivämääriä ja aikoja tarkasti ja luotettavasti erilaisissa kansainvälisissä ympäristöissä. Vaikka selaintuki on vielä kehittymässä, Temporal API:n hyödyt tekevät siitä oppimisen ja käyttöönoton arvoisen uusissa projekteissa. Ottamalla Temporal API:n käyttöön ja noudattamalla kansainvälistämisen parhaita käytäntöjä voit luoda sovelluksia, jotka tarjoavat saumattoman ja tarkan päivämäärä- ja aikakokemuksen käyttäjille ympäri maailmaa.

Lisätietoa

• Temporal API:n virallinen dokumentaatio
• MDN Web Docs aiheesta Temporal